Skip to content

Complete startup automation and external access fixes#1

Merged
Patel230 merged 19 commits intodevelopmentfrom
dev-startup-repair
Aug 17, 2025
Merged

Complete startup automation and external access fixes#1
Patel230 merged 19 commits intodevelopmentfrom
dev-startup-repair

Conversation

@mvalancy
Copy link
Copy Markdown
Member

Summary

This PR implements comprehensive startup automation for GraphDone, making it incredibly easy for developers to get up and running with a single command. Extensive work was done to handle common development environment issues automatically.

🚀 Key Improvements

One-Command Startup Experience:

  • New ./start launcher script with professional console output and automatic error handling
  • Automatic Node.js installation via nvm if not found
  • Automatic workspace dependency detection and repair
  • Smart port conflict resolution (switched from 3000/4000 to 3127/4127)
  • Docker permission detection with sudo fallback

Enhanced Development Scripts:

  • ./tools/setup.sh - Robust initial environment setup with error handling
  • ./tools/run.sh - Professional development server management with health monitoring
  • ./tools/cleanup.sh - Cleanup hanging processes and ports
  • ./tools/fix-workspace.sh - Comprehensive workspace dependency repair

External Access & Network Support:

  • Fixed Vite configuration for external hostname access
  • Dynamic hostname detection using os.hostname()
  • Support for Tailscale, .local domains, and custom hostnames
  • Proper network interface binding for remote development

🔧 Technical Fixes

Startup Script Reliability:

  • Automatic Node.js PATH detection and nvm loading
  • Workspace dependency validation and auto-repair
  • Prisma client generation when missing
  • Port cleanup before starting services
  • Service health monitoring with timeout handling

Network Configuration:

  • Changed default ports to 3127/4127 to avoid common conflicts
  • Added host: '0.0.0.0' for external interface binding
  • Dynamic allowedHosts with auto-detected hostname
  • Support for various network scenarios (local, VPN, Tailscale)

Error Handling:

  • Comprehensive error detection for common setup issues
  • Clear user guidance for Docker permissions and Node.js installation
  • Automatic fallback strategies for environment problems
  • Professional status displays and progress indicators

📚 Documentation Updates

  • Updated README.md with clear "One Command to Rule Them All" section
  • Added troubleshooting section for common issues
  • Documented all new scripts and their purposes
  • Clear prerequisites and setup instructions

🧪 Testing

  • Tested on remote servers via SSH
  • Verified external hostname access through Tailscale
  • Validated automatic error recovery scenarios
  • Confirmed workspace dependency repair functionality

💡 Developer Experience

This PR transforms GraphDone from requiring manual setup steps to a one-command experience:

git clone https://github.com/GraphDone/GraphDone-Core.git
cd GraphDone-Core
./start

The script automatically handles:

  • ✅ Node.js installation (if missing)
  • ✅ Docker permission issues
  • ✅ Workspace dependency problems
  • ✅ Port conflicts
  • ✅ Database setup and migrations
  • ✅ External network access
  • ✅ Professional status monitoring

🔄 Breaking Changes

  • Default ports changed from 3000/4000 to 3127/4127
  • Environment files updated with new port configuration
  • Vite configuration updated for external access

All changes are backward compatible and maintain existing functionality while adding robust automation.

Generated with significant development and testing effort for production-ready startup automation.

Matthew Valancy added 19 commits August 16, 2025 17:01
- Add *.tsbuildinfo to prevent committing incremental build files
- Add prisma/dev.db to exclude local database files
- Ensures cleaner repository without build artifacts
- Create environment files automatically with sensible defaults
- Add proper database health checks before proceeding
- Include Prisma client generation step
- Clean TypeScript build cache to prevent stale builds
- Improve reliability of initial setup process
- Add automatic setup detection and execution
- Implement proper database health checks
- Include Prisma client generation for reliability
- Add service readiness monitoring with health checks
- Display professional status box when all services are ready
- Provide clear URLs and helpful tips to users
- Add ./start script with colorful banner and clear progress indicators
- Add ./launch.sh as minimal quick-start alternative
- Both scripts provide automatic setup detection
- Improve user experience with clear messaging and guidance
- Make GraphDone accessible to users without reading documentation
- Replace multi-step setup with single ./start command
- Add clear explanation of automatic setup process
- Include direct URLs for all services with descriptions
- Add alternative launcher options for different user preferences
- Update contributing instructions to use new startup flow
- Improve user experience with clearer getting started guide
- Add interactive Node.js 18 installation using nvm when missing
- Provide comprehensive installation guides for all prerequisites
- Include automatic version upgrade prompts for outdated Node.js
- Add clear prerequisites section to README.md
- Enhance error messages with specific installation instructions
- Support multiple installation methods across different platforms
- Add automatic Docker permission detection and sudo fallback
- Provide clear instructions for fixing Docker group permissions
- Support sudo mode for users who haven't fixed permissions yet
- Remove obsolete 'version' field from docker-compose.yml
- Add troubleshooting section to README for common issues
- Auto-detect and handle permission issues in both setup and run scripts
- Add automatic nvm environment loading in run script
- Use subshells for directory changes to prevent cd errors
- Detect and handle case where Node.js is installed but not in PATH
- Provide clear instructions for shell restart when needed
- Add fallback error handling with helpful troubleshooting tips
- Export proper PATH when installing Node.js via nvm
- Use kill -9 for more reliable port cleanup
- Add automatic port cleanup before starting development servers
- Implement proper signal handling for clean shutdown
- Create standalone cleanup script for manual process cleanup
- Add port troubleshooting section to README
- Improve error handling and process management
- Web app: 3000 → 3127 (less commonly used port)
- GraphQL API: 4000 → 4127 (less commonly used port)
- Update all configuration files and scripts
- Update documentation and README with new URLs
- Port 3000 is heavily used by React dev servers and other tools
- These new ports are much less likely to conflict with existing services
- Add core package build step before starting dev servers
- Ensures workspace dependencies are properly resolved
- Prevents 'Cannot find module @graphdone/core' errors
- Core package must be built for other packages to import it correctly
- Enhance setup script to ensure proper workspace linking
- Add dependency checks to run script with automatic fixes
- Create fix-workspace.sh script for manual troubleshooting
- Add workspace dependency verification steps
- Include troubleshooting section in README for module errors
- Ensure core package is always built before starting servers
- Add automatic detection of workspace dependency issues
- Perform quick workspace repair when core package missing
- Rebuild core package and reinstall dependencies as needed
- Fall back to full setup if quick repair fails
- Users no longer need to run separate fix scripts
- One command (./start) now handles all common issues
- Include Node.js detection and nvm loading in start script
- Handle case where npm command not found due to PATH issues
- Ensure start script works even when Node.js not in PATH
- Provides consistent experience across different environments
- Include Prisma client generation in workspace repair
- Detect missing Prisma client and automatically regenerate
- Add Prisma client check to workspace dependency detection
- Ensure server starts without 'prisma generate' errors
- Complete end-to-end automation for all common setup issues
- Add host: '0.0.0.0' to Vite server configuration
- Enables access to development server from external connections
- Required for accessing GraphDone from outside localhost
- Allows testing with wget/curl from remote hosts
- Add allowedHosts: 'all' to Vite server configuration
- Fixes 'Blocked request. This host is not allowed' errors
- Enables access via Tailscale, VPN, and custom domain names
- Required for accessing GraphDone via hostname instead of IP
- Set host: true to allow all hostnames (including Tailscale)
- Removes explicit allowedHosts and disableHostCheck options
- Ensures external access works properly for remote development
- Import hostname from os module for dynamic detection
- Add common patterns for .local and .tailscale domains
- Removes hardcoded hostnames and IP addresses
@Patel230
Copy link
Copy Markdown
Member

Tested the code on local server and it's working fine: LP 2025-08-17 at 9 04 47 AM

LP 2025-08-17 at 9 08 39 AM

Tested the code on the development server, and it's working fine too:
LP 2025-08-17 at 9 05 13 AM

LP 2025-08-17 at 9 09 07 AM

Great work on the startup automation! 🚀

The ./start script is exactly what we needed - one command setup makes onboarding so much smoother. Really appreciate the automatic Node.js installation and Docker
permission handling.

Few quick notes:

  • Love the port change to 3127/4127 to avoid conflicts
  • The external access fix for Tailscale/VPN is perfect for remote development
  • Consider adding a --skip-auto flag for power users who want manual control
  • Maybe add some unit tests for these setup scripts?

The developer experience improvements are solid. This will save everyone a lot of setup headaches.

Looks Good To Me! ✅ Let's merge this and get everyone using the simplified setup.

@Patel230 Patel230 merged commit 26440cc into development Aug 17, 2025
@mvalancy mvalancy deleted the dev-startup-repair branch August 17, 2025 03:44
Patel230 added a commit that referenced this pull request Oct 27, 2025
Complete startup automation and external access fixes
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants